001 /**
002 * Java Gui Builder - A library to build GUIs using an XML file.
003 * Copyright 2002, 2003 (C) François Beausoleil
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either
008 * version 2.1 of the License, or (at your option) any later version.
009 *
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013 * Lesser General Public License for more details.
014 *
015 * You should have received a copy of the GNU Lesser General Public
016 * License along with this library; if not, write to the Free Software
017 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018 */
019
020 package jgb.builder;
021
022 import org.xml.sax.SAXException;
023
024 import java.util.Map;
025
026 /**
027 * The base interface that all TagHandlers must implement.
028 * <p>
029 * All {@link jgb.builder.Builder Builder} instances use
030 * {@link jgb.builder.TagHandler TagHandler} instances to parse
031 * the document's content.
032 * </p>
033 * <p>
034 * All methods of {@link jgb.builder.TagHandler TagHandler} are
035 * based on the equivalent {@link org.xml.sax.ContentHandler} interface.
036 * The difference is that the {@link jgb.builder.TagHandler TagHandler}
037 * interface prepends a <code>tagContext</code> parameter to all methods.
038 * This parameter is guaranteed to be the same accross all calls to all
039 * {@link jgb.builder.TagHandler TagHandler} methods.
040 * {@link jgb.builder.TagHandler TagHandler}s are encouraged to keep
041 * context information in this {@link java.util.Map Map} to refer to it later
042 * as other elements are encountered.
043 * </p>
044 * <p>
045 * For example usage of the <code>tagContext</code> parameter, look at the
046 * current implementation.
047 * </p>
048 * @see org.xml.sax.ContentHandler
049 * @since 0.1a
050 * @author Francois Beausoleil, <a href="mailto:fbos@users.sourceforge.net">fbos@users.sourceforge.net</a>
051 */
052 public interface TagHandler {
053 /**
054 * Key to access the context's current objects stack.
055 * <p>Initialized in {@link jgb.builder.Builder Builder}.</p>
056 * <p>Never removed</p>
057 * Contains: a reference to a {@link java.util.Stack Stack} object.<br />
058 */
059 public static final String CURRENT_OBJECTS_STACK_KEY = "builder.currentObjects.stack";
060
061 /**
062 * Key to access the context's current {@link jgb.builder.utils.ConstructorCall}
063 * object.
064 * <p>
065 * Use this key when implementing <code>TagHandler</code>s that must
066 * update information on how the current object will be instantiated
067 * (parameters to constructor, for instance).
068 * </p?
069 * <p>
070 * For an example, see
071 * {@link jgb.handlers.swing.ParameterTagHandler#exitElement() exitElement()}.
072 * </p>
073 * <p>Initialized in {@link jgb.handlers.swing.ObjectTagHandler ObjectTagHandler}.</p>
074 * <p>Removed in {@link jgb.handlers.swing.ParameterTagHandler ParameterTagHandler}.</p>
075 * <p>Contains: a reference to a {@link jgb.builder.utils.ConstructorCall ConstructorCall} object.</p>
076 */
077 public static final String CURRENT_PARM_ACC_KEY = "builder.currentConstruction.constructorCall";
078
079 /**
080 * Key to access the context's {@link java.util.Map Map} of built objects.
081 * <p>
082 * Use this key when referring to previously built objects in the current
083 * file.
084 * </p>
085 * <p>Initialized in {@link jgb.builder.Builder Builder}.</p>
086 * <p>Never removed</p>
087 * <p>Contains: a reference to a {@link java.util.Map Map} object.</p>
088 */
089 public static final String OBJECTS_MAP_KEY = "builder.objects";
090
091 /**
092 * Key to access the context's current window reference.
093 * <p>
094 * When the builder encounters a <window> element, it instantiates a
095 * window and saves the reference in the context. This way, descendants
096 * may use the context to get the current window, when they need it.
097 * </p>
098 * <p>Initialized in {@link jgb.handlers.swing.WindowTagHandler WindowTagHandler}.</p>
099 * <p>Removed in {@link jgb.handlers.swing.WindowTagHandler WindowTagHandler}.</p>
100 * <p>Contains: a reference to a {@link java.awt.Window Window} object. This depends
101 * on the <code>type</code> attribute that was encountered earlier on.</p>
102 */
103 public static final String CURRENT_WINDOW_KEY = "builder.current.window";
104
105 /**
106 * Key to access the context's current window's ID.
107 * <p>
108 * When the builder encounters a <window> element, it saves the
109 * element's ID in the context. This way, descendants may refer to the
110 * window's ID to get the object when they need it.
111 * </p>
112 * <p>Initialized in {@link jgb.handlers.swing.WindowTagHandler WindowTagHandler}.</p>
113 * <p>Removed in {@link jgb.handlers.swing.WindowTagHandler WindowTagHandler}.</p>
114 * <p>Contains: a reference to a {@link java.lang.String String} object.</p>
115 */
116 public static final String CURRENT_WINDOW_ID_KEY = "builder.current.window.id";
117
118 /**
119 * Key to access the stack of controls being built.
120 * <p>
121 * When the builder encounters a <controls> element, it pushes the
122 * current window's content pane on a stack, which it stores under this
123 * key. As new controls are encountered, they are pushed on the stack.
124 * Once all controls have been built, the stack should be empty, and
125 * will be removed.
126 * </p>
127 * <p>Initialized in {@link jgb.handlers.swing.ControlsTagHandler ControlsTagHandler}.</p>
128 * <p>Removed in {@link jgb.handlers.swing.ControlsTagHandler ControlsTagHandler}.</p>
129 * <p>Contains: a reference to a {@link java.util.Stack Stack} object.</p>
130 * @deprecated Replaced by {@link #CURRENT_OBJECTS_STACK_KEY}.
131 */
132 public static final String CONTROLS_STACK_KEY = "builder.current.window.controlsStack";
133
134 /**
135 * Key to access the context's {@link java.util.Map Map} of constants.
136 * <p>
137 * This map must contain two items per constant definition:
138 * </p>
139 * <ul>
140 * <li><constant fully qualified name><b>.class</b></li>
141 * <li><constant fully qualified name><b>.value</b></li>
142 * </ul>
143 * <p>
144 * This item will be used by
145 * {@link jgb.handlers.swing.ConstantTagHandler ConstantTagHandler} to
146 * find the map of constant names to values.
147 * </p>
148 * <p>Initialized in {@link jgb.builder.Builder Builder}.</p>
149 * <p>Never removed.</p>
150 * <p>Contains: a reference to a {@link java.util.Map Map} object.</p>
151 */
152 public static final String CONSTANTS_MAP_KEY = "builder.constants";
153
154 /**
155 * Key to access the object that has just been built.
156 * <p>
157 * Use this key when you need to refer to the object that has been built.
158 * This reference is valid until another object is being built, or the
159 * current scope terminates.
160 * </p>
161 * <p>Initialized in {@link jgb.handlers.swing.ObjectTagHandler ObjectTagHandler}.</p>
162 * <p>Removed in {@link jgb.handlers.swing.ObjectTagHandler ObjectTagHandler}.</p>
163 * <p>Contains: a reference to a {@link java.lang.Object Object} object
164 * (actually, the constructed object's class).</p>
165 * @deprecated Replaced by
166 * {@link jgb.handlers.swing.AbstractTagHandler#getCurrentObject() AbstractTagHandler.getCurrentObject()}.
167 * The default implementation should not use this key anymore.
168 */
169 public static final String CURRENT_OBJECT_KEY = "builder.currentObject.object";
170
171 /**
172 * Key to access the current construction's ID.
173 * <p>
174 * This key refers to the id attribute of the <object> element.
175 * </p>
176 * <p>Initialized in {@link jgb.handlers.swing.ObjectTagHandler ObjectTagHandler}.</p>
177 * <p>Removed in {@link jgb.handlers.swing.ObjectTagHandler ObjectTagHandler}.</p>
178 * <p>Contains: a reference to a {@link java.lang.String String} object.</p>
179 */
180 public static final String CURRENT_OBJECT_ID_KEY = "builder.currentObject.id";
181
182 /**
183 * Key to access the next control's constraints.
184 * <p>
185 * When the builder encounters <constraints>, it copies whatever
186 * was in the element's value and puts it in the context under this key.
187 * When the next controls are added, they will use these constraints.
188 * </p>
189 * <p>Initialized in {@link jgb.handlers.swing.ConstraintsTagHandler ConstraintsTagHandler}.</p>
190 * <p>Removed in {@link jgb.handlers.swing.ControlsTagHandler ControlsTagHandler}.</p>
191 * <p>Contains: a reference to a {@link java.lang.Object Object}.</p>
192 */
193 public static final String CURRENT_CONSTRAINTS_KEY = "builder.currentObject.constraints";
194
195 /**
196 * Key to access the current parameter or property name.
197 * <p>
198 * While building properties accessors and parameters, this key refers to
199 * the entity's name.
200 * </p>
201 * <p>Initialized in {@link jgb.handlers.swing.ParameterTagHandler ParameterTagHandler}
202 * or {@link jgb.handlers.swing.PropertyTagHandler PropertyTagHandler}</p>
203 * <p>Removed in {@link jgb.handlers.swing.ParameterTagHandler ParameterTagHandler}
204 * or {@link jgb.handlers.swing.PropertyTagHandler PropertyTagHandler}</p>
205 * <p>Contains: a reference to a {@link java.lang.String String} object.</p>
206 */
207 public static final String PROPERTY_NAME_KEY = "builder.currentConstruction.parm.name";
208
209 /**
210 * Key to access the current parameter or property class.
211 * <p>
212 * While building properties accessors and parameters, this key refers to
213 * the entity's class.
214 * </p>
215 * <p>Initialized in {@link jgb.handlers.swing.ParameterTagHandler ParameterTagHandler}
216 * or {@link jgb.handlers.swing.PropertyTagHandler PropertyTagHandler}</p>
217 * <p>Removed in {@link jgb.handlers.swing.ParameterTagHandler ParameterTagHandler}
218 * or {@link jgb.handlers.swing.PropertyTagHandler PropertyTagHandler}</p>
219 * <p>Contains: a reference to a {@link java.lang.Class Class} object.</p>
220 */
221 public static final String PARAMETER_CLASS_KEY = "builder.currentConstruction.parm.class";
222
223 /**
224 * Key to access the current parameter or property class.
225 * <p>
226 * While building properties accessors and parameters, this key refers to
227 * the entity's instantiated object.
228 * </p>
229 * <p>
230 * If the value property was set using <constant>, the class will
231 * be set to the class of the reference's class. If the value property
232 * was set using <ref>, the class will be set to the class of the
233 * reference.
234 * </p>
235 * <p>Initialized in {@link jgb.handlers.swing.ValueTagHandler ValueTagHandler},
236 * {@link jgb.handlers.swing.ConstantTagHandler ConstantTagHandler} or
237 * {@link jgb.handlers.swing.RefTagHandler RefTagHandler}.</p>
238 * <p>Removed in {@link jgb.handlers.swing.ValueTagHandler ValueTagHandler},
239 * {@link jgb.handlers.swing.ConstantTagHandler ConstantTagHandler} or
240 * {@link jgb.handlers.swing.RefTagHandler RefTagHandler}.</p>
241 * <p>Contains: a reference to a {@link java.lang.Object Object} object.</p>
242 */
243 public static final String PARAMETER_VALUE_KEY = "builder.currentConstruction.parm.value";
244
245 /**
246 * Key to access the last <methodCall>'s return value's class.
247 * <p>
248 * MethodCalls store the return value's class in this context property.
249 * </p>
250 * <p>Initialized in {@link jgb.handlers.swing.MethodCallTagHandler MethodCallTagHandler}.</p>
251 * <p>Removed in {@link jgb.handlers.swing.MethodCallTagHandler MethodCallTagHandler}.</p>
252 * <p>Contains: a reference to a {@link java.lang.Class Class} object.</p>
253 */
254 public static final String CALL_RETURN_CLASS_KEY = "builder.methodCall.returnValue.class";
255
256 /**
257 * Key to access the last <methodCall>'s return value.
258 * <p>
259 * MethodCalls store the return value in this context property.
260 * </p>
261 * <p>Initialized in {@link jgb.handlers.swing.MethodCallTagHandler MethodCallTagHandler}.</p>
262 * <p>Removed in {@link jgb.handlers.swing.MethodCallTagHandler MethodCallTagHandler}.</p>
263 * <p>Contains: a reference to a {@link java.lang.Object Object} object.</p>
264 */
265 public static final String CALL_RETURN_VALUE_KEY = "builder.methodCall.returnValue.value";
266
267 /**
268 * Key to access the context's {@link jgb.builder.TagHandlerFactory TagHandlerFactory} stack.
269 * <p>
270 * The top of this stack must always be the current factory. It is illegal
271 * for this stack to become empty. The default builder stores it's factory
272 * on this stack when it starts up. Elements which update this stack
273 * must ensure to always leave it as it was when they are done. Usually,
274 * this means pushing a new factory when opening the element, and popping
275 * the same factory when closing the element.
276 * </p>
277 * <p>Initialized in {@link jgb.builder.Builder Builder}.</p>
278 * <p>Removed in {@link jgb.builder.Builder Builder}.</p>
279 * <p>Contains: a reference to a {@link java.util.Stack Stack}.</p>
280 */
281 public static final String TAG_HANDLER_FACTORY_STACK_KEY = "builder.tagFactory.stack";
282
283 /**
284 * Key to access the current document's locator.
285 * <p>
286 * This locator key might not even exist because locators are the
287 * responsibility of the SAX parser, and are not required to provide
288 * one.
289 * </p>
290 * <p>Initialized in {@link jgb.builder.Builder Builder}.</p>
291 * <p>Never removed.</p>
292 * <p>Contains: a reference to a {@link org.xml.sax.Locator}.</p>
293 */
294 public static final String DOCUMENT_LOCATOR_KEY = "builder.locator";
295
296 /**
297 * Model keys
298 */
299 public static final String MODEL_ID = "builder.model.id";
300
301 /**
302 * Model keys
303 */
304 public static final String CURRENT_MODEL_ATTRIBUTE = "builder.model.attribute";
305
306 /**
307 * Model keys
308 */
309 public static final String CURRENT_MODEL_ADAPTER = "builder.model.adapter";
310
311 /**
312 * The builder itself
313 */
314 public static final String WINDOW_KEY = "builder";
315
316 /**
317 * The {@link jgb.builder.WindowContext WindowContext} which is building
318 * the current window.
319 */
320 public static final String WINDOW_CONTEXT_KEY = "builder.windowcontext";
321
322 /**
323 * Signals the start of a new element in the XML source.
324 * <p>
325 * The {@link jgb.builder.Builder Builder} object will call this method
326 * whenever it encounters a new element.
327 * </p>
328 * @param qName The qualified name of the element as it was encountered.
329 * @param tagContext A map of context information that is kept accross
330 * all calls to {@link jgb.builder.TagHandler TagHandler}s.
331 * @param atts A map of the attributes that were passed to this element.
332 */
333 void startElement(String qName, Map tagContext, Map atts) throws SAXException;
334
335 /**
336 * Signals the end of an element in the XML source.
337 * <p>
338 * The {@link jgb.builder.Builder Builder} object will call this method
339 * whenever an element ends.
340 * </p>
341 * @param qName The qualified name of the element as it was encountered.
342 * @param tagContext A map of context information that is kept accross
343 * all calls to {@link jgb.builder.TagHandler TagHandler}s.
344 */
345 void endElement(String qName, Map tagContext) throws SAXException;
346 }